# README

Paper:		How to detect heterogeneity in conjoint experiments
Authors:	Thomas Robinson (LSE; t.robinson7@lse.ac.uk)
		Raymond Duch (Nuffield College; raymond.duch@nuffield.ox.ac.uk)

This directory contains all material necessary to replicate the main paper and 
appendix.

There is one replication script:

    1. replication.R contains all analyses (main and appendix)

Evidence of successful running of this script, via knitr::spin("replication.R"), 
is included as `replication.html`.

Descriptions of each variable in the two datasets are included in the 
`codebook.pdf` file.

The current source files for the accompanying software, cjbart, are also 
included in this directory.

## DOCKER CONTAINER

We also provide a Dockerfile, which setups an RStudio server instance with 
system and package dependencies pre-installed. To use this Dockerfile,
from the command line you first need to build the image, by running the following
code from the main replication directory:

  docker build --platform linux/amd64 -t cjbart . 

Then, to run the container, enter the following command:

  docker run --platform linux/amd64 --rm -ti -e DISABLE_AUTH=true -e ROOT=true -p 8787:8787 cjbart
  
The RStudio interface will then be accessible from your browser at http://localhost:8787/

To close the container, simply press ctrl+c from the command line.

## REPLICATION ENVIRONMENT
    
### System:
    * Ryzen 2700x processor
    * 64GB RAM
    * R version 4.3.1 (2023-06-16)
    * x86_64-pc-linux-gnu (64-bit)
    * Ubuntu 22.04.2 LTS

### R, RNG, and package requirements (incl. versions):

Random number generation:
	RNG:     L'Ecuyer-CMRG 
	Normal:  Inversion 
	Sample:  Rejection 

Attached base packages:
	stats     		graphics  		grDevices 		utils     		datasets  		
	methods   		base     

Other attached packages:
	cjbart_0.3.1          	BART_2.9.4              survival_3.2-13       	nnet_7.3-17           	nlme_3.1-155
	ggrgl_0.1.0		grf_2.3.0             	cregg_0.4.0           	xtable_1.8-4          	broom_1.0.5
	rpart.plot_3.1.1      	rpart_4.1.19		randomForestSRC_3.2.2 	ggpubr_0.6.0		cowplot_1.1.1
	forcats_1.0.0         	stringr_1.5.0         	dplyr_1.1.2          	purrr_1.0.1		readr_2.1.4
        tidyr_1.3.0           	tibble_3.2.1         	ggplot2_3.4.2         	tidyverse_2.0.0		lubridate_1.9.2

Loaded via a namespace (and not attached):

	Rdpack_2.4              DBI_1.1.2               sandwich_3.0-1          rlang_1.1.1            
	magrittr_2.0.3          compiler_4.3.1          systemfonts_1.0.4       vctrs_0.6.3            
	RTriangle_1.6-0.12      httpcode_0.3.0          pkgconfig_2.0.3         crayon_1.5.2           
	fastmap_1.1.1           backports_1.4.1         magick_2.7.4            ellipsis_0.3.2         
	labeling_0.4.2          devout_0.2.9            utf8_1.2.3              ggstance_0.3.6         
	promises_1.2.0.1        tzdb_0.4.0              ragg_1.2.5              cryogenic_0.1.0        
	xfun_0.39               jsonlite_1.8.7          later_1.3.1             parallel_4.3.1         
	data.tree_1.0.0         R6_2.5.1                stringi_1.7.12          RColorBrewer_1.1-3     
	car_3.1-2               lmtest_0.9-40           Rcpp_1.0.11             knitr_1.43             
	zoo_1.8-9               base64enc_0.1-3         httpuv_1.6.11           Matrix_1.4-0           
	splines_4.3.1           timechange_0.2.0        tidyselect_1.2.0        rstudioapi_0.15.0      
	abind_1.4-5             curl_5.0.1              lattice_0.20-45         shiny_1.7.4.1          
	withr_2.5.0             evaluate_0.21           devoutrgl_0.1.0         survey_4.2-1           
	polyclip_1.10-4         pillar_1.9.0            carData_3.0-5           DiagrammeR_1.0.10      
	generics_0.1.2          hms_1.1.3               munsell_0.5.0           scales_1.2.1           
	glue_1.6.2              gdtools_0.3.3           tools_4.3.1             gfonts_0.2.0           
	decido_0.3.0            ggsignif_0.6.4          visNetwork_2.1.2        rgl_1.2.1              
	grid_4.3.1              mitools_2.4             rbibutils_2.2.13        colorspace_2.1-0       
	snowcrash_0.1.4         cli_3.6.1               DiceKriging_1.6.0       textshaping_0.3.6      
	fontBitstreamVera_0.1.1 fansi_1.0.4             gtable_0.3.3            rstatix_0.7.2          
	digest_0.6.33           fontquiver_0.2.1        crul_1.4.0              farver_2.1.1           
	htmlwidgets_1.6.2       htmltools_0.5.5         triangular_0.1.8        lifecycle_1.0.3        
	mime_0.12               fontLiberation_0.1.0

## RUNTIMES

Main paper: 	Approx. 2 hours 30 minutes
Appendix: 	Approx. 1.21 days

## NOTES
    
    (0) The cjbart package developed as part of this paper underwent additional
    development since the analytical results in this paper were submitted (August 2022). 
    We have therefore updated all code to be consistent with the latest CRAN 
    version of this software at the point of acceptance. As a result, there are small 
    differences in the appendix results. We document these changes in the 
    `NOTES TO REPLICATOR.txt` file.

    (1) Figure 1 relies on R packages not available on CRAN. Commands to install these 
    packages are included (commented out) in the main replication script, in Section 0.
    
    Rendering Figure 1 (b) requires OpenGL libraries on the system before installing
    the rgl package.
  
    (2) This analysis deals with large amounts of data, and therefore on systems
    with low memory and/or compute power, the runtimes can be very long. The main
    script times the execution by section, which is printed at the end of the 
    output. Note, the appendix contains intensive Monte Carlo simulations.

    This replication's peak RAM usage, running the script exactly as stated, is approximately
    50GB of RAM. Memory usage could be reduced, at the expense of runtime, by reducing
    the number of cores used.
  
    (3) All filepaths are relative to the main replication folder

